| Server IP : 121.121.20.254 / Your IP : 216.73.217.89 Web Server : Microsoft-IIS/10.0 System : Windows NT WEB-SERVER 10.0 build 20348 (Windows Server 2022) AMD64 User : IUSR ( 0) PHP Version : 8.3.28 Disable Function : NONE MySQL : ON | cURL : ON | WGET : OFF | Perl : OFF | Python : OFF | Sudo : OFF | Pkexec : OFF Directory : C:/Program Files/LibreOffice/help/en-US/text/sbasic/shared/ |
Upload File : |
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<base href="../../../../">
<noscript><meta http-equiv="refresh" content="0; URL=../../../../en-US/noscript.html"></noscript>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Using Procedures, Functions or Properties</title>
<link rel="shortcut icon" href="media/navigation/favicon.ico">
<link type="text/css" href="normalize.css" rel="Stylesheet">
<link type="text/css" href="prism.css" rel="Stylesheet">
<link type="text/css" href="default.css" rel="Stylesheet">
<script type="text/javascript" src="polyfills.js"></script><script type="text/javascript" src="languages.js"></script><script type="text/javascript" src="en-US/langnames.js"></script><script type="text/javascript" src="flexsearch.debug.js"></script><script type="text/javascript" src="prism.js"></script><script type="text/javascript" src="help2.js" defer></script><script type="text/javascript" src="a11y-toggle.js" defer></script><script type="text/javascript" src="paginathing.js" defer></script><script type="text/javascript" src="en-US/bookmarks.js" defer></script><script type="text/javascript" src="en-US/contents.js" defer></script><script type="text/javascript" src="help.js" defer></script><meta name="viewport" content="width=device-width,initial-scale=1">
</head>
<body>
<header id="TopLeftHeader"><a class="symbol" href="en-US/text/shared/05/new_help.html"><div></div></a><a class="logo" href="en-US/text/shared/05/new_help.html"><p dir="auto">LibreOffice 24.2 Help</p></a><div class="dropdowns"><div class="modules">
<button type="button" data-a11y-toggle="modules-nav" id="modules" aria-haspopup="true" aria-expanded="false" aria-controls="modules-nav">Module</button><nav id="modules-nav" hidden=""></nav>
</div></div></header><aside class="leftside"><input id="accordion-1" name="accordion-menu" type="checkbox"><label for="accordion-1" dir="auto">Contents</label><div id="Contents" class="contents-treeview"></div></aside><div id="SearchFrame"><div id="Bookmarks">
<input id="search-bar" type="search" class="search" placeholder="Search in bookmarks for chosen module" dir="auto"><div class="nav-container" tabindex="0"><nav class="index" dir="auto"></nav></div>
</div></div>
<div id="DisplayArea" itemprop="softwareHelp" itemscope="true" itemtype="http://schema.org/SoftwareApplication">
<a name="bm_id3149456"></a>
<meta itemprop="keywords" content="procedures">
<meta itemprop="keywords" content="functions,using">
<meta itemprop="keywords" content="variables,passing to procedures, functions, properties">
<meta itemprop="keywords" content="parameters,for procedures, functions or properties">
<meta itemprop="keywords" content="parameters,passing by reference or value">
<meta itemprop="keywords" content="variables,scope">
<meta itemprop="keywords" content="scope of variables">
<meta itemprop="keywords" content="GLOBAL variables">
<meta itemprop="keywords" content="PUBLIC variables">
<meta itemprop="keywords" content="PRIVATE variables">
<meta itemprop="keywords" content="functions,return value type">
<meta itemprop="keywords" content="return value type of functions">
<a name="procedures"></a>
<h1 id="hd_id3149456" dir="auto">
<a name="UsingSubs_h1"></a>Using Procedures, Functions and Properties</h1>
<p id="par_id3150767" class="paragraph" dir="auto">The following describes the basic use of procedures, functions and properties in LibreOffice Basic.</p>
<div class="note">
<div class="noteicon" dir="auto"><img src="media/icon-themes/res/helpimg/note.svg" alt="note" style="width:40px;height:40px;"></div>
<div class="notetext"><p id="par_id3151215" dir="auto">When you create a new module, LibreOffice Basic automatically inserts a <span class="literal">Sub</span> called "<span class="literal">Main</span>". This default name has nothing to do with the order or the starting point of a LibreOffice Basic project. You can also safely rename this <span class="literal">Sub</span>routine.</p></div>
</div>
<br>
<div class="note">
<div class="noteicon" dir="auto"><img src="media/icon-themes/res/helpimg/note.svg" alt="note" style="width:40px;height:40px;"></div>
<div class="notetext"><p id="par_id314756320" dir="auto">Some restrictions apply for the names of your public variables, subroutines, functions and properties. You must not use the same name as one of the modules of the same library.</p></div>
</div>
<br>
<p id="par_id3154124" class="paragraph" dir="auto">Procedures (<span class="literal">Sub</span>routines) functions (<span class="literal">Function</span>) and properties (<span class="literal">Property</span>) help you maintaining a structured overview by separating a program into logical pieces.</p>
<p id="par_id3153193" class="paragraph" dir="auto">One benefit of procedures, functions and properties is that, once you have developed a program code containing task components, you can use this code in another project.</p>
<h2 id="hd_id3153770" dir="auto">Passing Variables to Procedures, Functions or Properties</h2>
<p id="par_id3155414" class="paragraph" dir="auto">Variables can be passed to both procedures, functions or properties. The <span class="literal">Sub</span> <span class="literal">Function</span> or <span class="literal">Property</span> must be declared to expect parameters:</p>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
Sub SubName(Parameter1 As TYPENAME, Parameter2 As TYPENAME,...)
' your code goes here
End Sub
</code></pre></div>
<p id="par_id3152577" class="paragraph" dir="auto">The <span class="literal">Sub</span> is called using the following syntax:</p>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
[Call] SubName( [Parameter1:=]Value1, [Parameter2:=]Value2, ...)
</code></pre></div>
<p id="par_id3147124" class="paragraph" dir="auto">The parameters passed to a <span class="literal">Sub</span> must fit to those specified in the <span class="literal">Sub</span> declaration.</p>
<p id="par_id3147397" class="paragraph" dir="auto">The same process applies to a <span class="literal">Function</span>. In addition, functions always return a function result. The result of a function is defined by assigning the return value to the function name:</p>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
Function FunctionName(Parameter1 As TYPENAME, Parameter2 As TYPENAME,...) As TYPENAME
' your code goes here
FunctionName=Result
End Function
</code></pre></div>
<p id="par_id3153839" class="paragraph" dir="auto">The <span class="literal">Function</span> is called using the following syntax:</p>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
Variable = FunctionName( [Parameter1:=]Value1, [Parameter2:=]Value2, ...)
</code></pre></div>
<p id="par_id981584288549909" class="paragraph" dir="auto">Properties combine the syntax of procedures and functions. A <span class="literal">Property</span> usually requires up to one parameter.</p>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
Private _IsApproved As TYPENAME
Property Get IsApproved As TYPENAME
' your code goes here
IsApproved = some_computation
End Property
Property Let IsApproved(value As TYPENAME)
' your code goes here
_IsApproved = computed_value
End Property
</code></pre></div>
<p id="par_id3153389" class="paragraph" dir="auto">The <span class="literal">Property</span> is called using the following syntax:</p>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
var = IsApproved
IsApproved = some_value
</code></pre></div>
<div class="tip">
<div class="noteicon" dir="auto"><img src="media/icon-themes/res/helpimg/tip.svg" alt="tip" style="width:40px;height:40px;"></div>
<div class="notetext"><p id="par_idN107B3" dir="auto">You can also use the fully qualified name to call a procedure, function or property:<br> <span class="literal">[Call] Library.Module.Macro()</span>, where <span class="literal">Call</span> is optional.<br> For example, to call the Autotext macro from the Gimmicks library, use the following command:<br> <span class="literal">Gimmicks.AutoText.Main()</span></p></div>
</div>
<br>
<h2 id="hd_id3156276" dir="auto">Passing Variables by Value or Reference</h2>
<p id="par_id3155765" class="paragraph" dir="auto">Parameters can be passed to a procedure, a function or a property either by reference or by value. Unless otherwise specified, a parameter is always passed by reference. That means that a <span class="literal">Sub</span>, a <span class="literal">Function</span> or a <span class="literal">Property</span> gets the parameter and can read and modify its value.</p>
<p id="par_id3145640" class="paragraph" dir="auto">If you want to pass a parameter by value insert the key word <span class="literal">ByVal</span> in front of the parameter when you call a <span class="literal">Sub</span>, a <span class="literal">Function</span> or a <span class="literal">Property</span>, for example:</p>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
Function ReadOnlyParms(ByVal p2, ByVal p2)
' your code goes here
End Function
result = ReadOnlyParms(parm1, parm2)
</code></pre></div>
<p id="par_id3149258" class="paragraph" dir="auto">In this case, the original content of the parameter will not be modified by the <span class="literal">Function</span> since it only gets the value and not the parameter itself.</p>
<h2 id="hd_id161584366585035" dir="auto">Defining Optional Parameters</h2>
<p id="par_id31584367006971" class="paragraph" dir="auto">Functions, procedures or properties can be defined with optional parameters, for example:</p>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
Sub Rounding(number, Optional decimals, Optional format)
' your code goes here
End Sub
</code></pre></div>
<h2 id="hd_id951622730099178" dir="auto">Positional or Keyword Arguments</h2>
<p id="par_id591622730131786" class="paragraph" dir="auto">When you call a function or a subroutine, you may pass its arguments by position or by name. Passing by position means just listing the arguments in the order in which the parameters are defined in the function or subroutine. Passing by name requires you to prefix the argument with the name of the corresponding parameter followed by a colon and an equal sign (<span class="literal">:=</span>). Keyword arguments may appear in any order. Refer to Basic Replace() function for such examples.</p>
<a name="kwargs"></a>
<p id="par_id591622730284162" class="paragraph" dir="auto">When needing to pass less parameters, use keywords arguments. Passing values for fewer parameters by position requires to supply values for all parameters before them, optional or not. This ensures that the values are in the correct positions. If you pass the parameters by name - using keyword arguments - you may omit all other intermediate arguments.</p>
<h2 id="hd_id3150982" dir="auto">Scope of Variables</h2>
<p id="par_id3149814" class="paragraph" dir="auto">A variable defined within a <span class="literal">Sub</span>, a <span class="literal">Function</span> or a <span class="literal">Property</span>, only remains valid until the procedure is exited. This is known as a "local" variable. In many cases, you need a variable to be valid in all procedures, in every module of all libraries, or after a <span class="literal">Sub</span>, a <span class="literal">Function</span> or a <span class="literal">Property</span> is exited.</p>
<h3 id="hd_id3154186" dir="auto">Declaring Variables Outside a <span class="literal">Sub</span> a <span class="literal">Function</span> or a <span class="literal">Property</span>
</h3>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
Global VarName As TYPENAME
</code></pre></div>
<p id="par_id3145258" class="paragraph" dir="auto">The variable is valid as long as the LibreOffice session lasts.</p>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
Public VarName As TYPENAME
</code></pre></div>
<p id="par_id3150088" class="paragraph" dir="auto">The variable is valid in all modules.</p>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
Private VarName As TYPENAME
</code></pre></div>
<p id="par_id3152994" class="paragraph" dir="auto">The variable is only valid in this module.</p>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
Dim VarName As TYPENAME
</code></pre></div>
<p id="par_id3150368" class="paragraph" dir="auto">The variable is only valid in this module.</p>
<h3 id="hd_id5097506" dir="auto">Example for private variables</h3>
<p id="par_id8738975" class="paragraph" dir="auto">Enforce private variables to be private across modules by setting <span class="literal">CompatibilityMode(True)</span>.</p>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
' ***** Module1 *****
Private myText As String
Sub initMyText
myText = "Hello"
Print "In module1 : ", myText
End Sub
' ***** Module2 *****
'Option Explicit
Sub demoBug
CompatibilityMode( True )
initMyText
' Now returns empty string
' (or raises error for Option Explicit)
Print "Now in module2 : ", myText
End Sub
</code></pre></div>
<h3 id="hd_id3154368" dir="auto">Saving Variable Content after Exiting a <span class="literal">Sub</span> a <span class="literal">Function</span> or a <span class="literal">Property</span>
</h3>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
Static VarName As TYPENAME
</code></pre></div>
<p id="par_id3154486" class="paragraph" dir="auto">The variable retains its value until the next time the a <span class="literal">Function</span>, <span class="literal">Sub</span> or <span class="literal">Property</span> is entered. The declaration must exist inside a <span class="literal">Sub</span>, a <span class="literal">Function</span> or a <span class="literal">Property</span>.</p>
<h2 id="hd_id3155809" dir="auto">Specifying the Return Value Type of a <span class="literal">Function</span> or a <span class="literal">Property</span>
</h2>
<p id="par_id3149404" class="paragraph" dir="auto">As with variables, include a type-declaration character after the function name, or the type indicated by <span class="literal">As</span> and the corresponding data type at the end of the parameter list to define the type of the function or property's return value, for example:</p>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
Function WordCount(WordText As String) As Integer
</code></pre></div>
<a name="relatedtopics"></a><div class="relatedtopics">
<p class="related" itemprop="mentions" dir="auto"><a name="related"></a><span class="emph">Related Topics</span>
</p>
<div class="relatedbody" itemprop="mentions">
<div class="embedded"><p class="embedded" dir="auto"><a target="_top" href="en-US/text/sbasic/shared/compatibilitymode.html">CompatibilityMode() Function</a></p></div>
<div class="embedded"><p class="embedded" dir="auto"><a target="_top" href="en-US/text/sbasic/shared/03103300.html">Option Explicit Statement</a></p></div>
<p id="N0237" class="paragraph" dir="auto"><a target="_top" href="en-US/text/sbasic/shared/03104100.html">Optional keyword</a></p>
<p id="N0238" class="paragraph" dir="auto"><a target="_top" href="en-US/text/sbasic/shared/property.html">Property Statement</a></p>
<p id="N0239" class="paragraph" dir="auto"><a target="_top" href="en-US/text/sbasic/shared/03103500.html">Static Statement</a></p>
</div>
</div>
</div>
<div id="DonationFrame"></div>
<footer><div id="DEBUG" class="debug">
<h3 class="bug">Help content debug info:</h3>
<p dir="auto">This page is: <a href="https://opengrok.libreoffice.org/xref/help/source/text/sbasic/shared/01020300.xhp" target="_blank">/text/sbasic/shared/01020300.xhp</a></p>
<p dir="auto">Title is: Using Procedures, Functions or Properties</p>
<p id="bm_module" dir="auto"></p>
<p id="bm_system" dir="auto"></p>
<p id="bm_HID" dir="auto"></p>
</div></footer>
</body>
</html>